3.18.6 Article Buttons

People often include references to other stuff in articles, and it would be nice if Gnus could just fetch whatever it is that people talk about with the minimum of fuzz when you hit RET or use the middle mouse button on these references.

Gnus adds buttons to certain standard references by default: Well-formed URLs, mail addresses, Message-IDs, Info links, man pages and Emacs or Gnus related references. This is controlled by two variables, one that handles article bodies and one that handles article heads:

gnus-button-alist

This is an alist where each entry has this form:

(regexp button-par use-p function data-par)

regexp

All text that match this regular expression (case insensitive) will be considered an external reference. Here’s a typical regexp that matches embedded URLs: ‘<URL:\\([^\n\r>]*\\)>’. This can also be a variable containing a regexp, useful variables to use include gnus-button-url-regexp and gnus-button-mid-or-mail-regexp.

button-par

Gnus has to know which parts of the matches is to be highlighted. This is a number that says what sub-expression of the regexp is to be highlighted. If you want it all highlighted, you use 0 here.

use-p

This form will be evaled, and if the result is non-nil, this is considered a match. This is useful if you want extra sifting to avoid false matches. Often variables named gnus-button-*-level are used here, See Article Button Levels, but any other form may be used too.

function

This function will be called when you click on this button.

data-par

As with button-par, this is a sub-expression number, but this one says which part of the match is to be sent as data to function.

So the full entry for buttonizing URLs is then

("<URL:\\([^\n\r>]*\\)>" 0 t gnus-button-url 1)

gnus-header-button-alist

This is just like the other alist, except that it is applied to the article head only, and that each entry has an additional element that is used to say what headers to apply the buttonize coding to:

(header regexp button-par use-p function data-par)

header is a regular expression.

3.18.6.1 Related variables and functions

gnus-button-*-level

See Article Button Levels.

gnus-button-url-regexp

A regular expression that matches embedded URLs. It is used in the default values of the variables above.

gnus-button-man-handler

The function to use for displaying man pages. It must take at least one argument with a string naming the man page.

gnus-button-mid-or-mail-regexp

Regular expression that matches a message ID or a mail address.

gnus-button-prefer-mid-or-mail

This variable determines what to do when the button on a string as ‘foo123@bar.invalid’ is pushed. Strings like this can be either a message ID or a mail address. If it is one of the symbols mid or mail, Gnus will always assume that the string is a message ID or a mail address, respectively. If this variable is set to the symbol ask, always query the user what to do. If it is a function, this function will be called with the string as its only argument. The function must return mid, mail, invalid or ask. The default value is the function gnus-button-mid-or-mail-heuristic.

gnus-button-mid-or-mail-heuristic

Function that guesses whether its argument is a message ID or a mail address. Returns mid if it’s a message IDs, mail if it’s a mail address, ask if unsure and invalid if the string is invalid.

gnus-button-mid-or-mail-heuristic-alist

An alist of (RATE . REGEXP) pairs used by the function gnus-button-mid-or-mail-heuristic.

gnus-article-button-face

Face used on buttons.

gnus-article-mouse-face

Face used when the mouse cursor is over a button.

See Customizing Articles, for how to buttonize articles automatically.